AOI for R

Defining an Area of Interest (AOI)

An area of interest (AOI) is the geographic extent. It helps confine the unit of work to a geographic area, and helps to not only prioritize and define research and subsetting efforts, but improves reproducabilty across studies. ‘AOI` is an R package that lets users define an AOI through a common query and return a ’SpatialPolygon’ of that area.

Three parameters can be used to define a query: state, county, and clip_unit. This page illustrates how these parameters can be used define – and refine – a query.

Method 1: Defining an AOI by state

An AOI can be defined by a state name or abbreviation:

CA = getAOI(state = 'CA')

A query can also be defined by multiple states provided as a vector:

WestCoast = getAOI(state = c("Oregon", "Washington", "CA"))

Method 2: Defining an AOI by county

Defining an AOI by county requires a state as well:

EP = getAOI(state = "CO", county = "El Paso")

Multiple counties can be queried if provided as a vector:

centralCoast = getAOI(state ="CA", county = c("Santa Barbara", "San Luis Obispo", "Ventura"))

Method 3: Defining an AOI with a clip_unit

In HydroData a clip_unit is user defined region. Most commonly a bounding box or a supplied shapefile - both of which can be input as a clip_unit.

The clip_unit list()

To define a bounding box clip_unit has four inputs given as a list:

Location
Bounding box height (in miles)
Bounding box width (in miles)
location origin (default = ‘center’)

Again, all clip_unit inputs must be provided as a list. It is also important to note that order DOES matter if each parameter is not explicitly assigned (eg h = 10). Examples for each input follow:

1. Location

A Location is the first input in clip_unit list and can be given as a colloquial name (character string) or as a (lat/long) pair (numeric). Names are geocoded by the Google API via the dismo R package.

Grand Canyon Location example:

Here we query an AOI surrounding the Grand Canyon, using both the colloquial name, and the (lat/long) pair found with a Google search. Notice slightly different locations are generated:

GC_name = getAOI(clip_unit = list("grand canyon", 10, 10))

GC_lat_lon = getAOI(clip_unit = list(36.0544, -112.1401, 10, 10))

2. Bounding box height and width

Once a location is specified, the next two needed values are a bounding box height and width (in miles). The first entry defines height and the second width:

National Water Center bounding box diminsions example:

nwc.tall = getAOI(clip_unit = list("National Water Center, AL", 30, 10))
nwc.wide = getAOI(clip_unit = list("National Water Center, AL", 10, 30))

3. Origin

With a location, height, and width defined the relationship of the box to the location is needed. By default (and in the previous examples) each bounding box was generated using the location as a centroid. You can change this by adding a final argument to the clip_unit list specifying where the location lies in reference to the box. Options include ‘center’, ‘lowerleft’, ‘lowerright’, ‘upperleft’, ‘upperright’:

UCSB origin example:

ucsb.c =  getAOI(clip_unit = list("UCSB", 10, 10, "center"))
ucsb.ul = getAOI(clip_unit = list("UCSB", 10, 10, "upperleft"))
ucsb.ur = getAOI(clip_unit = list("UCSB", 10, 10, "upperright"))
ucsb.ll = getAOI(clip_unit = list("UCSB", 10, 10, "lowerleft"))
ucsb.lr = getAOI(clip_unit = list("UCSB", 10, 10, "lowerright"))

Clip_unit by User Shapefile

A user supplied shapefile can be used as input for the clip_unit parameter in lieu of a list() bounding box.

Santa Monica (user shapefile example):

#Read in shapefile of all Los Angeles Communities
LA = rgdal::readOGR("shp/LA.shp", verbose = FALSE)
#Subset Santa Monica
SM = LA[LA$LABEL_CITY == 'Santa Monica',] %>% spTransform(aoiProj)
#Define AOI
AOI = getAOI(clip_unit = SM)

Finding and refining an AOI

One on the hardest aspects of defining an AOI is deciding on the query parameters (eg the location, width and height). To help with this the AOI package has a check function that can be used to define OR refine AOI queries.

If you have no idea about the constraints of your AOI you can run check() alone:

check()

Doing so brings up a map centered on the United States (panning is available). Zooming to your general AOI, you can use the tools in the lower right hand corner of the map to mark locations to get lat/long, and measure distances. These values can them be input directly into the getAOI() call.

Give it a try!

The check() function can also be chained to existing AOI call to immediately see the region being queried:

getAOI(clip_unit = list("San Luis Obispo", 10, 10 )) %>% check()

Using the tabs in the upper right corner allow you to toggle between base maps to better understand the area you are defining.

Give it a try!

Use Cases

Now that you know how to define, view and refine an AOI, check out some packages and/or services that are using, or could use the AOI package for spatial subsetting calls:

HydroData
nwm
FlowlineFinder
FedData
nhdplusTools

Support

Package development is supported with funds from the UCAR COMET program; the NOAA National Water Center; and the University of California, Santa Barbara (UCSB).